# Buddy Companion Guide Snow CLI includes a local terminal companion managed by the `/buddy` command. A buddy is stored locally, appears in the terminal UI, and can react through small local bubbles while you work. Back to: [Catalogue](./0.Catalogue.md) --- ## Overview The buddy companion is designed as a lightweight local companion for coding sessions. - **Local state**: Buddy data is stored under the user's local Snow configuration directory. - **Terminal UI**: The companion can appear near the input area when enabled. - **Interactive commands**: You can hatch, pet, rename, customize appearance, talk to, mute, unmute, inspect, and reset the buddy. - **Random traits**: Rarity, eye, hat, shiny state, and stats are rolled when hatching. - **Optional species selection**: You may choose the species during hatching. If omitted, the species is random. - **Post-hatch customization**: Use `/buddy set` to precisely update hat, eye, body color, rarity, shiny, personality, species, and stats without hand-editing config files. --- ## Command Summary ```bash /buddy /buddy status /buddy hatch [name] [--species=species] [--list-species] [--personality=text] /buddy pet /buddy rename /buddy set [--hat=...] [--eye=...] [--color=...] [--rarity=...] [--shiny=true|false] [--species=...] [--personality=...] [--debugging=1-10] /buddy set --list /buddy customize ... # alias of set /buddy say /buddy profile [list|current|default|reset|] /buddy mute /buddy unmute /buddy reset ``` `/buddy` without arguments is the same as `/buddy status`. --- ## Hatch a Buddy Use `/buddy hatch` to create your companion. ```bash /buddy hatch /buddy hatch Mochi ``` When no name is provided, Snow CLI chooses a default name. When no species is provided, the species is random. ### Specify the Species You can specify the species with `--species=`: ```bash /buddy hatch Mochi --species=cat /buddy hatch Orbit --species=dragon ``` Only the species is fixed by this option. The hat remains random, and rarity, eye, shiny state, and stats are still rolled normally. ### List Available Species Use either command to print all supported species: ```bash /buddy hatch --list-species /buddy hatch --species=list ``` Available species: ```text duck, goose, blob, chicken, basketball, cat, dragon, octopus, owl, penguin, turtle, snail, ghost, axolotl, capybara, cactus, robot, rabbit, mushroom, chonk, fox, panda, raccoon, unicorn, whale, hamster, teapot, rocket, laptop, moon, cloud, lantern, treasure, book, star, coffee, snowman ``` ### Add a Personality You can provide a personality with `--personality=`: ```bash /buddy hatch Pip --species=fox --personality=curious, loyal, and fond of tests ``` The personality text may contain spaces. Everything after `--personality=` is treated as the personality description. --- ## Interact with Your Buddy ### Check Status ```bash /buddy status ``` The status output includes the buddy's name, species, rarity, personality, hat, eye, mute state, AI profile, hatch time, and stats. ### Pet the Buddy ```bash /buddy pet ``` This triggers a short local UI reaction. If a buddy reply model is configured, the companion may also respond in its bubble. ### Talk to the Buddy ```bash /buddy say hello /buddy say how are the tests looking? ``` The buddy reply is separate from the main assistant response. The companion answers as the local buddy in the UI bubble. ### Choose the Buddy AI Profile Buddy AI replies use the current Snow profile by default. You can pin Buddy to a specific profile, list available profiles, show the current selection, or reset Buddy back to following the current Snow profile. ```bash /buddy profile list /buddy profile current /buddy profile default /buddy profile reset /buddy profile work ``` The selected Buddy AI profile is persisted in the global Buddy state file under the local Snow configuration directory. When no Buddy-specific profile is set, switching the main Snow profile also changes the configuration used by Buddy AI replies. ### Rename the Buddy ```bash /buddy rename Noodle ``` Renaming only changes the buddy's name. Species, rarity, hat, eye, personality, hatch time, and stats remain unchanged. ### Customize Appearance and Personality After hatching, use `/buddy set` (or the alias `/buddy customize`) to precisely update the existing buddy. You do not need `/buddy reset`, and you should not hand-edit `buddy.json`. ```bash # List available hats / eyes / rarities / species / colors / stats /buddy set --list # Common form: --key=value /buddy set --hat=crown --eye=✦ --color=cyan --rarity=legendary --shiny=true # Compact form is also supported /buddy set hat=crown eye=✦ color=cyan rarity=legendary shiny=true # Custom color (named / hex / reset to default) /buddy set --color=magenta /buddy set --color=#0af /buddy set --color=default # Freeform eyes (preset or 1–2 Unicode characters) /buddy set --eye=♥ # Adjust personality, species, and stats (1-10) /buddy set --personality=calm, shiny, and gently reminds you to commit /buddy set --species=fox /buddy set --debugging=10 --patience=9 --wisdom=9 ``` Supported fields: | Field | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `name` | Name (or use `/buddy rename`) | | `personality` | Personality text | | `species` | Species; must be a lowercase supported name | | `hat` | Hat, e.g. `crown`, `beanie`, `wizard` | | `eye` | Eye character: presets like `✦`/`◉`/`·`/`♥`, or any 1–2 Unicode chars | | `color` | Body color override: named color (e.g. `cyan`) / `#RGB` / `#RRGGBB`; `default`/`clear`/`reset` restores species/shiny default | | `rarity` | `common` / `uncommon` / `rare` / `epic` / `legendary` | | `shiny` | `true` / `false` / `on` / `off`, etc. | | stats | `debugging`, `patience`, `chaos`, `wisdom`, `snark` (1–10) | Notes: - Only the fields you provide are updated; omitted fields stay unchanged. - Invalid values error out and print available options. - Unchanged values report that no valid changes were provided. - Agents and scripts should prefer the control-plane command `buddy.set` instead of editing `~/.snow/buddy.json` directly. --- ## Mute, Unmute, and Reset ### Mute ```bash /buddy mute ``` Muting hides the UI companion and removes buddy context from prompts until you unmute it. ### Unmute ```bash /buddy unmute ``` Unmuting shows the buddy again and allows companion context to be used. ### Reset ```bash /buddy reset ``` Reset removes the current buddy. Use `/buddy hatch` again to create a new one. A new hatch rolls a new companion; if you want a specific species again, pass `--species=`. --- ## Examples ```bash # Hatch a random buddy with a random name /buddy hatch # Hatch a random species with a custom name /buddy hatch Mochi # Hatch a cat named Mochi; hat and other traits remain random /buddy hatch Mochi --species=cat # Show all supported species /buddy hatch --list-species # Hatch a fox with a custom personality /buddy hatch Pip --species=fox --personality=curious, loyal, and fond of tests # Pet and talk to the buddy /buddy pet /buddy say nice work today # Customize appearance after hatch /buddy set --list /buddy set --hat=crown --eye=✦ --color=cyan --rarity=legendary --shiny=true /buddy set --color=#0af /buddy set --eye=♥ /buddy set --debugging=10 --patience=9 # Pin Buddy AI replies to a profile /buddy profile list /buddy profile work # Hide the buddy temporarily /buddy mute /buddy unmute ``` --- ## Notes - Only one buddy can exist at a time. Use `/buddy reset` before hatching a new one. - Species names are lowercase and must match the available list. - If an unknown species is provided, Snow CLI prints the available species list. - Choosing a species at hatch does not choose a hat; hats still roll randomly at hatch. To lock a look afterward, use `/buddy set`. - `/buddy set` and `/buddy customize` are equivalent. - `/buddy profile reset` and `/buddy profile default` clear the Buddy-specific AI profile so Buddy follows the current Snow profile again.